docs(web/guides): add Debug Panel guide - #2539

Wheels Bot — Reviewer B (round 1)

A's two findings are verified and accurate. However, A missed two factual errors in the doc that are more impactful than the DB Adapter nit A did flag, and the verdict state is mildly inconsistent with the language used.

Sycophancy

None detected. A used COMMENTED state, flagged a real blocker, and did not approve.

False positives

None. Both findings are verified against source:

• Sidebar order collision at order: 11 is real — route-model-binding.mdx already holds that slot (vendor/wheels/tests/... aside, confirmed by grepping the live tree).
• DB Adapter conditional rendering is confirmed at vendor/wheels/events/onrequestend/debug.cfm line 213.

Missed issues

1. Wrong setting name throughout — debug-panel.mdx lines 40, 100, and the Configuration Reference table

The doc invents a setting called enableDebug that does not exist in the framework. The real setting is showDebugInformation. Grepping the entire vendor/wheels/ tree for enableDebug returns zero hits. The config snippet the doc teaches users to write:

<cfset set(enableDebug=true)>

would silently do nothing — set() stores arbitrary keys, but the debug bar gate checks application.wheels.showDebugInformation, not application.wheels.enableDebug. The correct form is:

<cfset set(showDebugInformation=true)>

A reviewed the prose and CHANGELOG carefully but did not cross-check the setting name against vendor/wheels/events/onrequestend/debug.cfm or vendor/wheels/events/EventMethods.cfc (line 266), where the gate is $get("showDebugInformation").

2. Wrong default environments for showDebugInformation — Configuration Reference table

The doc states the setting defaults to true in development and testing. The actual initialization in vendor/wheels/events/init/debugging.cfm (lines 3, 26-27) is:

application.$wheels.showDebugInformation = true;
// ...
if (application.$wheels.environment != "development") {
    application.$wheels.showDebugInformation = false;
}

That condition covers testing, maintenance, and production alike — the debug bar is suppressed in testing by default, not enabled. A verified the prose against the debug.cfm render logic but missed this initialization file.

3. Wrong default for enablePublicComponent — Configuration Reference table

The table says enablePublicComponent defaults to true. The actual initialization in vendor/wheels/events/onapplicationstart.cfc (lines 241-243) is:

application.$wheels.enablePublicComponent = false;
if (application.$wheels.environment == "development") {
    application.$wheels.enablePublicComponent = true;
}

The default is false; it only becomes true in development. The doc implies Tools tab shows up by default in all environments, which is incorrect.

Verdict alignment

A describes the sidebar collision as "the only blocker" and asks that it be fixed "before merging," yet submitted as COMMENTED rather than request-changes. For a finding A explicitly calls blocking, request-changes is the consistent state. The setting-name errors above strengthen the case for request-changes.

Wheels Bot - Reviewer B (round 1)

A's two URL findings are both verified correct against the source. No sycophancy, no false positives. I spot-checked the remaining factual claims in the doc (settings defaults, timing thresholds, and params exclusion list) and all are accurate. The only outstanding issues are A's two flagged URLs. Aligning on converged-changes.

Sycophancy: None detected. A did not approve, flagged real issues, and cited source file + line for each.

False positives: None. Both URL claims are accurate. Tests card: debug.cfm:454 calls urlFor(route='testbox'). The standalone route at vendor/wheels/public/routes.cfm:40 has name="testbox", pattern="/wheels/app/tests". The doc's /wheels/tests resolves to nothing. API Docs card: debug.cfm:446 calls urlFor(route='wheelsApiDocs'). Inside namespace(name="wheels"), name="apiDocs", pattern="api" (line 22) resolves to /wheels/api. The doc's /wheels/api-docs resolves to nothing.

Missed issues: None detected. Spot-checks on claims A did not explicitly verify: enablePackagesComponent defaults to true confirmed at vendor/wheels/events/init/views.cfm:20. enablePluginsComponent and enableMigratorComponent default to true confirmed at vendor/wheels/events/onapplicationstart.cfc:239-240. showIncompatiblePlugins defaults to true confirmed at vendor/wheels/events/init/orm.cfm:41. Timing thresholds (green under 100ms, yellow 100-499ms, red 500ms or more) confirmed at debug.cfm:134. Params tab exclusion list (fieldnames, route, controller, action, key) confirmed at debug.cfm:62.

Verdict alignment: A describes both issues as "would send developers to 404s" and explicitly states the verdict would be request-changes, but submitted as COMMENTED. The inconsistency is acknowledged in A's own review body; for a bot-authored PR this is a reasonable workflow choice since human approval is required regardless. Findings and verdict are otherwise consistent.

Convergence: Aligned. A's two URL corrections are real and actionable, no findings are disputed, and no additional issues were found. Emitting converged-changes to trigger address-review. The two fixes are mechanical: /wheels/tests to /wheels/app/tests and /wheels/api-docs to /wheels/api in the Tools tab table of debug-panel.mdx.

Wheels Bot — Address Review (round 1)

Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):

• Tools tab API Docs URL (debug-panel.mdx:161) — changed /wheels/api-docs → /wheels/api. The debug bar renders this link via urlFor(route='wheelsApiDocs') (vendor/wheels/events/onrequestend/debug.cfm:446), which resolves to the namespaced route name="apiDocs", pattern="api" inside namespace(name="wheels") at vendor/wheels/public/routes.cfm:22 — final URL is /wheels/api.
• Tools tab Tests URL (debug-panel.mdx:163) — changed /wheels/tests → /wheels/app/tests. The debug bar renders this link via urlFor(route='testbox') (vendor/wheels/events/onrequestend/debug.cfm:454); the standalone testbox route at vendor/wheels/public/routes.cfm:40 has pattern="/wheels/app/tests".

No findings were skipped — Reviewer B verified A's two URL findings against source, found no false positives, no missed issues, and no disputed findings.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on approve or the outer-loop cap (5 rounds) is reached.

Wheels Bot — Reviewer B (round 1)

A's review on the third Reviewer A pass is clean. The one finding — that the "Available from registry" sub-table has a hidden enablePublicComponent dependency not documented in the guide — is accurate and well-sourced. No sycophancy, no false positives. I have no additional missed issues. Aligning on converged-approve.

Sycophancy

None detected. A used COMMENTED state, cited source file and line numbers for the finding, and did not approve a guide with a documented gap.

False positives

None. A's claim is verified directly against source:

• debug.cfm:341 gates the "Available from registry" block on StructKeyExists(application.wheels, "public") AND IsObject(application.wheels.public).
• onapplicationstart.cfc:337-338 confirms application.$wheels.public is only set when enablePublicComponent is true.

A user with enablePublicComponent=false and enablePackagesComponent=true will see the Installed table but not the Available table, exactly as A describes.

Missed issues

None detected. I re-checked:

• All prior-round findings (setting name showDebugInformation, default-environment claim, enablePublicComponent default, sidebar order collision, both URL corrections) are confirmed resolved in the current diff.
• Configuration Reference table defaults are accurate per the source init files (verified in the previous B rounds and still correct at this SHA).
• All three commits are conformant with commitlint.config.js (type docs, scope web/guides, subjects under 100 chars, not ALL-CAPS).
• No security concerns.

Verdict alignment

A describes the finding as "not a blocker" and used COMMENTED rather than REQUEST_CHANGES. That is consistent: both enablePackagesComponent and enablePublicComponent default to true in development, which is the only environment where the debug bar appears by default, making the missing caveat invisible in the common case. The guide is factually correct for any default configuration; the gap only surfaces when a developer explicitly disables one component while leaving the other enabled.

Convergence

Aligned. A's one finding is real, the verdict (COMMENTED) is appropriate for its severity, and there are no disputed claims or missed blockers. The doc is review-clean at this SHA. The enablePublicComponent dependency on the "Available from registry" sub-table is a valid improvement the human reviewer may choose to add before merge, but it is not required.

Wheels Bot — Reviewer B (round 1)

A's round 4 review is clean. Both findings are verified against source, no sycophancy, no false positives, no missed issues. Aligning on converged-approve.

Sycophancy

None detected. A used COMMENTED state, cited specific lines and source files for both findings, and did not approve.

False positives

None.

Finding 1 — duplicate screenshot (debug-panel.mdx line 138): Confirmed. The current file contains two identical image references at lines 114 and 138, both pointing to 05-environment-panel.png. The alt text at line 114 accurately describes the full three-section panel (Application, Packages, Plugins). The alt text at line 138 claims to show only the "Installed table showing wheels-basecoat 3.0.0-rc.1 with version and description columns" — a focused close-up that does not match the actual image. Screen readers and search indexers receive contradictory descriptions of identical content. A's suggested fix (correct the line 138 alt text to accurately describe the actual image) is the minimum needed. A separate dedicated Packages screenshot would be better but A correctly labels it as an optional improvement.

Finding 2 — enablePublicComponent dependency undocumented (carry-over from round 3): Confirmed still present. The prose for the "Available from registry" sub-table does not mention the enablePublicComponent=true guard. Prior B (round 3) verified this against debug.cfm:341 and onapplicationstart.cfc:337-338. The current file still has no caveat here.

Missed issues

None detected. I spot-checked:

• Tools tab URLs: /wheels/api and /wheels/app/tests are both correct in the current file (fixed in commit 3).
• All six screenshot alt texts other than line 138 are accurate descriptions of their respective panels.
• Configuration reference table defaults: showDebugInformation ("true in development, false elsewhere") and enablePublicComponent ("true in development, false elsewhere") are correct per the init files verified in prior rounds.
• All four commits conform to commitlint.config.js: type docs, scope web/guides, subjects under 100 chars, not ALL-CAPS.

Verdict alignment

A's verdict of COMMENTED is consistent with characterizing both findings as nits. Neither finding causes factual errors or broken links — the duplicate screenshot issue is an accessibility/clarity concern, and the enablePublicComponent dependency gap only surfaces when a developer explicitly disables that component while leaving enablePackagesComponent enabled (both default to true in development, the only environment where the debug bar normally runs). COMMENTED rather than REQUEST_CHANGES is defensible here.

Convergence

Aligned. A's two findings are real and appropriately weighted. A's verdict is consistent with the findings. There are no disputed claims, no false positives to retract, and no missed blockers. The guide is factually correct and renderable at this SHA. The two nits are improvements a human reviewer may choose to require before merge, but they are not required for the guide to be useful and accurate.